/****

    activequant - activestocks.eu

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

	
	contact  : contact@activestocks.eu
    homepage : http://www.activestocks.eu

****/
package org.activequant.dao;

import java.util.List;

import org.activequant.core.domainmodel.InstrumentSpecification;
import org.activequant.core.domainmodel.index.IndexComposition;
import org.activequant.core.types.TimeStamp;

/**
 * Regular CRUD functionality for index composition, plus useful finders.<br/>
 * An interface. Extends the IDaoSupport&lt;IndexComposition&gt; interface. Defines the following methods:
 * <ul>
 * <li>IndexComposition findByIndexSpec(InstrumentSpecification spec, TimeStamp byThisTime);</li>
 * <li>List&lt;IndexComposition&gt; findByIndexSpecAndTimeInterval(InstrumentSpecification spec, TimeStamp startTime, TimeStamp endTime);</li>
 * <li>List&lt;InstrumentSpecification&gt; findByComponent(InstrumentSpecification spec, TimeStamp byThisTime); </li>
 * <li>List&lt;InstrumentSpecification&gt; findByComponentAndTimeInterval(InstrumentSpecification spec, TimeStamp startTime, TimeStamp endTime);</li>
 * </ul>
 * <br>
 * <b>History:</b><br>
 *  - [06.08.2008] Created (Mike Kroutikov)<br>
 *  - [10.08.2008] Updated finders, removed a typo (Wessel de Roode)<br>
 *
 *  @author Mike Kroutikov
 */
public interface IIndexCompositionDao extends IDaoSupport<IndexComposition> {

	/**
	 * Locates Index by its instrument specification (remember: we identify index by
	 * an instrument specification. Since index composition change over time, one
	 * index spec can have a time series of IndexCompositions associated with it).
	 * <p>
	 * This finder locates most current composition relative to the given point in time.
	 * 
	 * @param spec index instrument spec.
	 * @param byThisTime point in time we are interested in.
	 * 
	 * @return index composition object, or null if none found.
	 */
	IndexComposition findByIndexSpec(InstrumentSpecification spec, TimeStamp byThisTime);

	/**
	 * Locates time series of index composition objects for the given index and
	 * time interval.
	 * 
	 * @param spec index instrument spec.
	 * @param startTime start time.
	 * @param endTime end time.
	 * 
	 * @return time series of index compositions, or null if none found.
	 */
	List<IndexComposition> findByIndexSpecAndTimeInterval(InstrumentSpecification spec, TimeStamp startTime, TimeStamp endTime);

	/**
	 * Locates all indexes that contain given instrument (as index component)
	 * by the given time.
	 * 
	 * @param spec instrument spec, describing the component.
	 * @param byThisTime time we are interested in.
	 * @return list of index specs. Note that we do not return list of
	 *         IndexComposition objects as this may often return all indices
	 *         (if spec corresponds to a popular stock), and loading all indices into
	 *         memory means loading corresponding components, which can
	 *         easily be all known stocks. 
	 */
	List<InstrumentSpecification> findByComponent(InstrumentSpecification spec, TimeStamp byThisTime); 

	/**
	 * Locates all indexes that contained given instrument any time during the
	 * specified time period.
	 * 
	 * @param spec component spec.
	 * @param startTime start time.
	 * @param endTime end time.
	 * @return list of index spec. We choose not to return IndexComposition objects
	 *         as this may lead to loading virtually all specs into memory.
	 */
	List<InstrumentSpecification> findByComponentAndTimeInterval(InstrumentSpecification spec, TimeStamp startTime, TimeStamp endTime);
	
}
